<!--
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
 the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-->
<html>
<head>
   <title>Package Documentation for org.apache.commons.validator</title>
</head>
<body bgcolor="white">
The Validator package provides validation for JavaBeans based on an xml file.
<br><br>
<a id="doc.Description"></a>
<div>
<a href="http://commons.apache.org/validator/dependencies.html">[Dependencies]</a>
<a href="#doc.Intro">[Introduction]</a>
<a href="#doc.Overview">[Overview]</a>
<a href="#doc.Resources">[Resources]</a>
<a href="#doc.Usage">[Usage Example]</a>
</div>

<a id="doc.Intro"></a>
<h2>Introduction</h2>

<p>A common issue when receiving data either electronically or from
user input is verifying the integrity of the data.  This work is
repetitive and becomes even more complicated when different sets
of validation rules need to be applied to the same set of data based
on locale for example.  Error messages may also vary by locale.
This package attempts to address some of these issues and
speed development and maintenance of validation rules.
</p>

<p>In order to use the Validator, the following basic steps are required:</p>
<ul>
   <li>Create a new instance of the
       <code>org.apache.commons.validator.Validator</code> class.  Currently
       Validator instances may be safely reused if the current ValidatorResources
       are the same, as long as
       you have completed any previous validation, and you do not try to utilize
       a particular Validator instance from more than one thread at a time.</li>
   <li>Add any <a href="#doc.Resources">resources</a>
       needed to perform the validations.  Such as the JavaBean to validate.</li>
   <li>Call the validate method on <code>org.apache.commons.validator.Validator</code>.</li>
</ul>

<a id="doc.Overview"></a>
<h2>Overview</h2>
<p>
   The Commons Validator is a basic validation framework that
   lets you define validation rules for a JavaBean in an xml file.
   Validators, the validation definition, can also be defined in
   the xml file.  An example of a validator would be defining
   what method and class will be called to perform the validation
   for a required field.  Validation rules can be grouped together
   based on locale and a JavaBean/Form that the rules are associated
   with.  The framework has basic support for user defined constants
   which can be used in some field attributes.
</p>
<p>
   Validation rules can be defined in an xml file which keeps
   them abstracted from JavaBean you are validating.  The
   property reference to a field supports nested properties
   using the Apache Commons BeanUtils
   (http://commons.apache.org/beanutils/) package.
   Error messages and the arguments for error messages can be
   associated with a fields validation.
</p>

<a id="doc.Resources"></a>
<h2>Resources</h2>
<p>
   After a Validator instance is created, instances of
   classes can be added to it to be passed into
   validation methods by calling the setParameter()
   method.  Below is a list of reserved parameters (class names).
</p>

<table border="1">
   <caption>Reserved Parameters</caption>
   <tr>
      <th>Class Name</th>
      <th>Validator Contstant</th>
      <th>Description</th>
   </tr>
   <tr>
      <td>java.lang.Object</td>
      <td>Validator.BEAN_PARAM</td>
      <td>JavaBean that is being validated</td>
   </tr>
   <tr>
      <td>java.util.Locale</td>
      <td>Validator.LOCALE_PARAM</td>
      <td>
         Locale to use when retrieving a FormSet.
         The default locale will be used if one
         isn't specified.
      </td>
   </tr>
   <tr>
      <td>org.apache.commons.validator.ValidatorAction</td>
      <td>Validator.VALIDATOR_ACTION_PARAM</td>
      <td>
         This is automatically added to a Validator's
         resources as a validation is being processed.
         If this class name is used when defining
         a method signature for a pluggable validator,
         the current ValidatorAction will be passed into
         the validation method.
      </td>
   </tr>
   <tr>
      <td>org.apache.commons.validator.Field</td>
      <td>Validator.FIELD_PARAM</td>
      <td>
         This is automatically added to a Validator's
         resources as a validation is being processed.
         If this class name is used when defining
         a method signature for a pluggable validator,
         the current Field will be passed into
         the validation method.
      </td>
   </tr>
</table>


<a id="doc.Usage"></a>
<h2>Usage Example</h2>
<p>
   This is a basic example setting up a required validator for
   a name bean.  This example is a working unit test (reference
   <code>org.apache.commons.validator.RequiredNameTest</code> and
   validator-name-required.xml located under validator/src/test).
</p>
<p>
   Create an xml file with your validator and validation rules.
   Setup your required validator in your xml file.<br>
   <br>
   <a href="#doc.Usage.xml">XML Example</a><br>
   <a href="#doc.Usage.validator">Validator Example</a><br>
   <a href="#doc.Usage.pluggableValidator">Pluggable Validator Example</a>
</p>

<a id="doc.Usage.xml"></a>
<h2>XML Example</h2>
<p>
   Definition of a 'required' pluggable validator.<br>
<pre>
&lt;form-validation&gt;
   &lt;global&gt;
      &lt;validator name="required"
         classname="org.apache.commons.validator.TestValidator"
         method="validateRequired"
         methodParams="java.lang.Object, org.apache.commons.validator.Field"/&gt;
   &lt;/global&gt;
   &lt;formset&gt;
   &lt;/formset&gt;
&lt;/form-validation&gt;
</pre>

<p>
   Add validation rules to require a first name and a last name.<br>
<pre>
&lt;form-validation&gt;
   &lt;global&gt;
      &lt;validator name="required"
         classname="org.apache.commons.validator.TestValidator"
         method="validateRequired"
         methodParams="java.lang.Object, org.apache.commons.validator.Field"/&gt;
   &lt;/global&gt;
<b>
   &lt;formset&gt;
      &lt;form    name="nameForm"&gt;
         &lt;field property="firstName" depends="required"&gt;
            &lt;arg0 key="nameForm.firstname.displayname"/&gt;
         &lt;/field&gt;
         &lt;field property="lastName" depends="required"&gt;
            &lt;arg0 key="nameForm.lastname.displayname"/&gt;
         &lt;/field&gt;
      &lt;/form&gt;
   &lt;/formset&gt;
</b>
&lt;/form-validation&gt;
</pre>

<a id="doc.Usage.validator"></a>
<h2>Validator Example</h2>
<p>
Excerpts from org.apache.commons.validator.RequiredNameTest
</p>
<pre>
InputStream in = this.getClass().getResourceAsStream("validator-name-required.xml");

// Create an instance of ValidatorResources to initialize from an xml file.
ValidatorResources resources = new ValidatorResources(in);
// Create bean to run test on.
Name name = new Name();

// Construct validator based on the loaded resources and the form key
Validator validator = new Validator(resources, "nameForm");
// add the name bean to the validator as a resource
// for the validations to be performed on.
validator.setParameter(Validator.BEAN_PARAM, name);

// Get results of the validation.
Map results = null;

// throws ValidatorException (catch clause not shown here)
results = validator.validate();

if (results.get("firstName") == null) {
   // no error
} else {
   // number of errors for first name
   int errors = ((Integer)results.get("firstName")).intValue();
}
</pre>

<a id="doc.Usage.pluggableValidator"></a>
<h2>Pluggable Validator Example</h2>
<p>
Validation method defined in the 'required' pluggable validator
(excerpt from org.apache.commons.validator.TestValidator).
</p>

<pre>
public static boolean validateRequired(Object bean, Field field) {
   String value = ValidatorUtil.getValueAsString(bean, field.getProperty());
      return GenericValidator.isBlankOrNull(value);
}
</pre>
</body>
</html>
